Skip to main content
Version: 25.03

Notifications

Industry Core covers the foundation for message-based data sharing using notifications. Notifications are already used in several use cases, but their implementation is not yet standardized. Most use cases, although, based their implementation on the first implementation, Traceability Quality Alerts & Investigations (on which Industry Core notifications are also based). Industry Core now defines an interoperable solution for sending and receiving notifications via connectors in Catena-X.

A general descriptions of notifications is given in the Architecture View of this KIT.

Process​

A notification is sent from one Catena-X partner - called sender - to another Catena-X partner - called receiver - using simple messages in JSON format via Catena-X connector, as shown in the following figure:

Notifications Flow

The data sharing is done via standardized connectors:

  • The receiver provides an asset in the connector to which notifications can be sent.
  • The sender initiates a contract negotiation for this asset to get a contract agreement and dataplane endpoint.
  • After a successful contract negotiation, the sender sends the notification via a HTTP POST request to the receiver via the dataplane endpoint from the contract agreement.
  • All notification operations are sent via the same asset using the same contract agreement.

Notification Data Format​

This section defines the data format for notifications:

Notifications must be compliant to the following JSON data format:

  {
    "header": {
      "messageId": "urn:uuid:f9a97301-a000-44dd-b9d8-78488a40c6bb",
      "context": "IndustryCore-DigitalTwinEventAPI-ConnectToParent:2.0.0",
      "sentDateTime": "2024-07-05T08:13:33.20733Z",
      "senderBpn": "BPNL000000000AAA",
      "receiverBpn": "BPNL000000000ZZZ",
      "expectedResponseBy": "2024-07-08T08:13:33.20733Z",
      "version": "3.0.0"
    },
    "content": {}
  }
  • The JSON schema for this schema is available here.
  • The property header must be compliant to the aspect model MessageHeaderAspect.
    • The messageId of a notification must uniquely identify a single message, therefore it must not be reused. No two notifications must share the same messageId. Only if a notification could not be sent because of data transfer errors, it MAY be re-sent with the same messageId.
    • It is recommended to use the following format (defined in the MessageHeaderAspect aspect model) for property context: <domain>-<subdomain>-<object>:<[major] version>
      • <domain> should be the name of the use case that defines the notification, e.g., IndustryCore.
      • <subdomain> should be the name of the notification API, e.g., DigitalTwinEventAPI.
      • <object> should be the name of the operation for which the notification is used, e.g., ConnectToParent.
      • Versioning only refers to major versions in both default and fallback cases.
      • This is recommended as it allows the notification receiver to freely choose what technology to use for the backend service. If this information is not encoded into the notifcation's context propoerty, a backend service like a message-queue technology will not know which notification operation was invoked by the sender as the endpoint information is not available in this case (compared to a REST API backend service).
  • Content and structure of the property content are not stanardized and must be defined by the use case defining the notifications API. A schema for this property must be defined as part of the OpenAPI specification of the notification API of the use case.

Aspect Model "MessageHeaderAspect"​

The Catena-X Message Header contains standardized attributes for message processing that are common across several use cases. It targets a minimal set of aspects that are required for overall message handling, but not for the processing of the business related payload part. By standardizing the message header structure, we support a harmonized modelling approach and re-use of concepts.

Identifier of Aspect Model: urn:samm:io.catenax.shared.message_header:3.0.0#MessageHeaderAspect

Aspect model in GitHub:

Example: Aspect Model MessageHeaderAspect 3.0.0​

{
  "header": {
    "messageId": "urn:uuid:f9a97301-a000-44dd-b9d8-78488a40c6bb",
    "context": "IndustryCore-DigitalTwinEventAPI-ConnectToParent:3.0.0",
    "sentDateTime": "2024-07-05T08:13:33.20733Z",
    "senderBpn": "BPNL000000000AAA",
    "receiverBpn": "BPNL000000000ZZZ",
    "expectedResponseBy": "2024-07-08T08:13:33.20733Z",
    "version": "3.0.0"
  },
}

Notification API​

The notification API of a use case must be defined with an OpenAPI specification. In this specification, all artefacts of the API are defined, e.g., name of the API, operation names, and notification data formats.

Preconditions and Dependencies​

  • The use case must standardize the notification API's name see Notification API Documentation
  • For a notification API, only the HTTP method POST is allowed.

API Specification​

  • Notification operations are modelled as endpoints (resources). For every operation, exactly one endpoint must be defined. This endpoint only supports the HTTP POST method.
  • The path URL should be the operation name with optional "-" as word separator.
  • The operationId must be the notification operation name. The same name should be used as <object> in the context property of the notification header. This redundancy is recommended to allow the notification receiver to freely choose what technology to use for the backend service, e.g, a REST API or message-queue technology.
  • The notification is the actual request body of the HTTP POST method. Its schema must also be defined in the specification.

Example: OpenAPI specification for Digital Twin Event API

Error Handling​

The following HTTP response codes should be defined for all notification operations:

CodeDescription
200OKIndicates that the request has succeeded.
4xxERRORThe notification cannot be processed.
5xxERRORThe notification cannot be processed.

A response body MAY also be defined (e.g., see Feedback notification operation in the example above).

These error codes are currently optional as the Catena-X connector does not yet return correct error messages from backend services. These error codes will become mandatory once the connector returns correct error messages from backend services.

Connector Asset Structure​

For a notification API, exactly one asset in the connector must be defined. All notifications operations of the API must be invoked through this asset.

  • The property http://purl.org/dc/terms/type must reference the name of the notification API as defined in the Catena-X taxonomy published under https://w3id.org/catenax/taxonomy.

Example of an asset definition for a notification API:

{
  "@id": "DigitalTwinEventAPI",
  "@type": "Asset",
  "properties": {
    "dct:type": {
      "@id": "cx-taxo:DigitalTwinEventAPI"
    },
    "cx-common:version": "3.0",
  },
  "dataAddress": {},
  "@context": {
    "dct": "http://purl.org/dc/terms/",
    "cx-taxo": "https://w3id.org/catenax/taxonomy#",
    "cx-common": "https://w3id.org/catenax/ontology/common#"
  }
}

Versioning​

Versioning of the notification API must follow the Catena-X guidelines for versioning. For every new major version of a notification API, a new connector asset must be created. If, e.g., a REST API is used as backend notification receiver, the incoming notifications can be fowarded to the correct REST API version via the corresponding connector asset, as depicted in the following figure:

Notifications Flow

The API's version is not only documented in the notification's connector asset (property https://w3id.org/catenax/ontology/common#version), but also in the OpenAPI specification as well as in a notification's context property.

Notification API Documentation​

A use case defining a notification API as part of its standard must document the following artifacts:

  • All notification data formats must be documented either as separate JSON schema or (also in JSON schema) as part of the notification API's OpenAPI specification.
  • The notification API must be documented with an OpenAPI specification and must be published according to TRG 1.08 - Interface documentation (APIs).
  • For a standardized use case, the name of the notification API (used in property http://purl.org/dc/terms/type) must be defined in the Catena-X taxonomy published under https://w3id.org/catenax/taxonomy.
  • The notification API asset in the connector must define necessary properties as defined in Connector Asset Structure.